SyncDataSource

SyncDataSource(datasource)

Send modified data records from a local database on the mobile device to one or more Target data sources.

All

datasource - required

Specifies the Data Source(s) to be acted on – click here to see how to specify Data Source(s) in this parameter.

You can specify multiple Data Sources separated by commas, e.g. "db1,db2,db3".

nothing

• Data records are marked as modified by calling UpdateCurrentRecord.

• When a record has been synced successfully it is marked as sent so that Digitise Apps does not sync the record again if SyncDataSource is called again or Synchronise is subsequently called.

• For database targets, the Data Source must have a Primary Key defined in the Data Source. If a record in the Target database has a Primary key which matches the Primary key in a record being synchronised, the existing record will be updated with the new data, otherwise a new record will be created in the Target database for the new data.

  You can specify multiple Primary Key fields in a single record if necessary, in which case the combination of all specified Primary Keys must be unique for each record.

  For Web Service targets it is the responsibility of the web service to interpret and process the data passed to it.

• If you specify multiple Data Sources in the call to this Method, each Data Source is processed separately. This means that Foreign Keys which take the form of identity fields will not be resolved across the data sources at the remote end. If you want to resolve this type of Foreign Key when uploading new records, use the Synchronise Method instead.

• For Web Service Data Sources without local storage (no Device Table Property defined and the Modify Action Online Property set to Direct) this Method will send the current record for the specified Data Source. (UpdateCurrentRecord must still be used to mark the record as modified.)

• This Method can't be used with Web API Data Sources.

• By default, a progress bar is displayed to show the progress of the upload and the user can cancel the sync whilst it is in progress. The SetApplicationOption Method allows you to reduce or turn off the messages displayed with the progress bar or to replace it with the device's standard busy indicator instead. It also allows you to disable/re-enable the ability to cancel the upload.

• If the user cancels the transfer, the calling Script will continue if data error reporting is OFF or stop and display a Script Error informing the user that they have cancelled the operation, if data error reporting is ON. Data error reporting is turned OFF using the SetDataErrorOn Method or On Error GoTo 0 statement and turned ON using the SetDataErrorOff Method or On Error Resume Next statement. If data error reporting is OFF, you can call GetLastDataError or GetLastError after SyncDataSource to check whether the user cancelled the operation. (See See also: below.)

• The Load After Sync Property allows you to force an automatic download of the Data Sources after a call to SyncDataSource. If you want to do this you can either set this Property or consider using the Synchronise Method instead.

• You may be able to reduce the amount of data being transferred by excluding data items from an upload which you know won't be updated by the user. For example, suppose you download photos for reference purposes only, in this case there is no need to upload them back to the remote database every time you do an upload. Each data item has a Read-Only Property which, if set to True, specifies that an existing value in the data item cannot be overwritten on the device; a value can only be entered into the data item in a new record. In addition, read-only data items are excluded from uploads using SyncDataSource (or Synchronise), allowing you to potentially reduce the amount of data in an upload. By default, the Property is set to False. Note that the value of this Property is ignored for Primary and Foreign Key fields when deciding whether data should be included in an upload and these fields are always included in the data uploaded, but the value is honoured in terms of updating local records. Primary Key fields, especially where the Identity property in the remote database is set to True, should usually be set to Read-only, otherwise the remote database might reject an attempt to update it.

• The Digitise app will pause and users will not be able to use the app whilst the data transfer takes place. If you are uploading a database Data Source and you want to be able to continue to use the app, see the Synchronise Method instead.

  You cannot make a call to SyncDataSource whilst an ongoing asynchronous data transfer is in progress.

• This Method isn't relevant for use with Custom Views.

• You cannot use this Method where you have stored data items such as photos and videos to file rather than in a local database table.

• On Android devices, note the following potential issues relating to large data objects, particularly photographs:

  • The uploading of records that contain multiple photo/video fields may fail due to a limitation in SQLite where the records cannot be read in their entirety from the database when the cumulative size of the data that they contain is over a certain size. This limit is undefined but appears to be tied to the version of Android and the amount of memory the device has available.

  • When downloading large binary fields (i.e. photos or videos) on lower power/memory devices the Digitise Apps Client may fail to download some large bitmaps/videos into the application database. An Out Of Memory error message will be displayed. The overall download should complete but some records may not contain the downloaded image/video data, having Null values in the columns where the Out Of Memory issue occurred. This problem may occur where you are trying to download photos/videos taken on one device, with a higher megapixel camera, to another less powerful device.